---
type: engineering-note
title: TDD with Scenario Evidence
description: Red-green-refactor where the red list is the flow's Scenarios table and green means the row cites its test.
tags: [engineering, skill, testing]
timestamp: {{DATE}}
---
<!-- ✂ docujoint template sample — replace with your own content, then delete this comment. -->
# TDD with Scenario Evidence

_Adapted for this knowledge base from
[Matt Pocock's engineering skills](https://github.com/mattpocock/skills/tree/main/skills/engineering)
(tdd)._

## When to use
Implementing or changing a flow, or working down the "untested paths" number
on the dashboard.

## The loop
1. **Red comes from the docs.** Pick an `untested` row in the flow's
   `## Scenarios` — unhappy paths first, they hide the defects. If the
   behaviour you're about to build has no scenario row, write the row first;
   an untestable scenario is an unspecified one.
2. **Write the failing test** named after the scenario, asserting its
   `Outcome` column literally.
3. **Green.** Implement until it passes.
4. **Cite.** Put the `test://` URI in the row's `Tests` cell — the row
   derives `covered`. This is the only place coverage is recorded; see
   [Testing Conventions](</Engineering/Testing Conventions.md>) and ADR
   [0001](</Engineering/Decisions/0001 Evidence First Testing.md>).
5. **Refactor** with the test green; the doc doesn't change because the
   behaviour didn't.

## The payoff
"Untested unhappy paths" on the dashboard is the shared red list — no
separate test backlog to maintain, and deleted tests surface as `drift`
instead of silently lying.

## Open questions